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ABSTRACT 

This  document  supplement*  TM-2337/101/00  by 
describing  the  input-output,  file-handling, 
and  library  functione  of  Q-32  LISP  1.$ 

Mod.  2.6.  It  alao  deacribea  differencea 
betveen  Mod.  2.6  and  the  previous  Nod.  2.5 
described  in  TM-23 37/1 02/00  dated  9  August 
1965. 
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1.  INTRODUCTION 

A  new  version  of  Q-32  LISP  1.5,  Model  2.6  has  been  operational  for  a  number  of 
months.  This  new  version  extends  the  capability  of  the  basic  system  described 
in  the  Q-32  LISP  Reference  Manual,  TM-2337/101/0C,  in  three  significant  ways. 
First,  a  new  scheme  for  input-output  is  available  that  permits  accec3  to  tele¬ 
type,  tapes,  disc,  and  CRT  devices  in  an  integrated  and  consistent  format. 

Second,  certain  modificatir-  .  hav-3  been  made  to  Evalquote  to  handle  the  new 
I/O  features.  Third,  free  space  and  array  space  have  been  increased  to  a  maxi¬ 
mum  of  nearly  (30,000)..  words  by  reducing  binary  program  space  to  nearly 
nothing,  and  augment ing  the  system  with  a  "growing  pain"  that  extends  binary  progri 
space  dynamically  by  preempting  array  space  when  needed. 

This  document  describes  these  nev  features  as  a  separate  document,  supplementing 
the  Q-32  LISP  Reference  Manual. 

2.  TABLE  OF  FUNCTIONS 

Table  1  contains  a  list  of  names  of  functions  described  in  this  document, 
together  with  function  types,  file  handling,  library  handling,  CRT  primitives, 
and  miscellaneous  functions. 

3.  INPUT-OUTPUT  CONCEPT  AND  OPERATION 

Model  2,6  USP  1.5  I/O  is  based  upon  a  set  of  primitive  functions  and  macros 
that  are  available  to  the  user.  Each  input  or  output  operation  references, 
either  implicitly  or  explicitly,  a  specific  file.  A  file  is  named  by  the  user 
and  associated  with  a  particular  device.  A  file  can  be  any  literal  atom,  e.g., 
INTAPE,  A6.,  etc.  The  LISP  meaning  of  the  term  "file"  is  the  same  as  the 
meaning  normally  assigned  by  a  time-sharing  system.  A  file  is  device-dependent 
but  direction-independent;  the  same  file  may  be  used  for  both  input  and  output 
and  can,  with  considerable  caution,  be  used  for  both  purposes  simultaneously. 

A  symbolic  file  consists  of  a  sequence  of  records,  only  one  of  which  is  ever 
in  main  memory  at  a  time,  thereby  reducing  buffer  storage  overhead.  Records 
consist  of  one  or  more  72-character  lines.  When  a  file  is  activated,  LISP 
dynamically  creates  from  array  space  the  buffer  storage  needed  to  hold  the 
current  record  of  the  file.  Also,  when  a  file  is  deactivated,  LISP  reclaims 
this  buffer  storage.  Many  files  may  be  active  concurrently, ^limited  only  by 
the  LISP  array  space  and  t;-?  time-sharing  devices  available. 


• 

Whenever  a  LISP  program  is  loaded  and  set  into  operation,  all  previously 
declared  files  (i.e.,  files  in  existence  at  the  *ime  the  program  was  saved) 
are  removed,  and  the  system  starts  off  with  only  a  single  teletype  file 
declared,  named  "TTY. 
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Table  1,  Functions  Discussed  in  this  Document 


Page 


Function  Raae 

No.  of  Arguments 

Function  Type 

No. 

•I0INIT 

0 

System  initialisation 

17 

•IOSHUT 

1 

System  initialization 

17 

LOADEXP 

1 

Library  loading 

1#? 

OPEN 

2  or  3 

Macro 

7 

OPENFILE 

3 

File  primitive 

19 

PLOT 

3 

CRT  buffer  filling 

12 

POSITION 

2 

file  positioning 

11 

PRIN1,  PRIN0  1 
"PINT,  PRINTCHj 

2 

Printing 

1U 

•RATOM,  READ  \ 
READ1,  READCH  j 

0 

Reading 

13 

READCRT 

2 

Light  pen  read 

15 

READFILE 

1 

Library  handling 

16 

PRINTCRT 

2 

CRT  display  output 

15 

PHINTFILE 

2 

Library  handling 

16 

RD6 

1 

Read  select 

10 

SHUT 

1  or  2 

Macro 

9 

•SHUTF 

2 

File  primitive 

9 

STSRPRI 

0 

Output 

13 

*SUPV 

0 

System  supervisor 

17 

TABIN 

1 

Reading 

12 

TABOUT 

1 

Printing 

12 

TEREAD 

0 

Reading 

13 

TERPRI 

0 

Printing 

12 

•TEVALQT 

2 

Eval quote 

17 

WRS 

1 

Write  select 

10 

I 


♦ 
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To  access  a  file,  the  user  must  first  select  the  file,  either  for  reading  or 
for  writing.  The  user's  program  always  accesses  the  same  file  for  each  call 
to  standard  LISP  I/O  primitives,  e.g.,  PRINT,  READ,  TERPRI,  etc.  To  access 
another  file,  that  file  must  be  activated,  (The  system  supervisor  always  uses 
the  input  teletype  console,  regardless  of  user  file  selection.) 

This  scheme  allows  LISP  programs  to  be  written  in  a  device-independent  manner. 
A  program  is  composed  which  evaluates  I/O  read  and  print  primitives  as  neces¬ 
sary  without  immediate  concern  as  to  the  source  or  destination  of  the  informa¬ 
tion.  Once  composed,  the  program  can  be  exercised  from  a  teletypewriter  file 
one  moment,  and  from  tape  or  disc  files  at  a  later  time  by  simply  activating 
and  selecting  such  files  in  higher  level  programs  or  at  the  top  level  itself. 

3.1  FILE  ACTIVATION 

Before  a  file  can  be  selected  for  reading  or  writing,  it  must  first  be  acti¬ 
vated.  This  activation  can  most  easily  be  done  using  the  macro  OPEN, 

OPEN  (f  dm) 

OPEN  is  a  LISP  macro  that  expands,  using  the  function  *0PENF,  intc  the  primi¬ 
tive  OPENFILE,  described  in  Section  5.  It  returns  as  its  value  a  list  of  all 
currently  active  file  names.  Here,  f  is  the  user-specified  name  of  the  file 
be^ng  activated;  it  is  a  literal  atom  whose  first  six  characters  are  used  for 
internal  identification  between  LISP  and  the  time-sharing  system.  The  argu¬ 
ment  d  specifies  the  device  associated  with  the  file  f.  While  the  optional 
parameter  m  is  used  to  indicate  the  nature  of  the  file  to  be  created,  the 
permissible  values  of  d  and  n  are  given,  together  with  their  meanings,  in  the 
following  table. 


Value  of  d  Device  Value  of  a  Meaning 


TTY 

Teletype 

•» 

DISC  or  DISK 

disc  unit 

nev  file 

PERM 

file  already  in  inventory 

0  (numeric  aero) 

tape 

WRITE 

scratch  tape,  reed/write 

number  n  *  7 

tape 

- 

tape  reel  n,  read  only 

WRITF 

tape  reel  n,  read/write 

number 

-  or  LOW 

680  character  maximum 

1  f  n  t  6 

1 

CRT 

MEDIUM 

1360  character  maximum 

_ 

HIGH 

2000  character  maximum 
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If  greater  control  over  file  activation  is  desired,  the  user  may  always  use 
the  primitive  OPENFILE,  OPEN  is  provided  as  a  convenience,  and  presupposes 
values  in  the  macro  expansion  to  OPENFILE.  These  values  are  tabulated  below: 


Unit 

Record  Size 

Internal  Buffer  Size 

Unit  Reservation 

TTY 

1  line 

10  words 

none 

Tape 

30  lines 

300  words 

1  tape  drive 

DISC 

1*1-51  lines 

512  words 

1  track 

Some  examples  of  the  use  of  OnEN  are  given  below: 


Example 

•ansmame 

OPEN(TTYFILE  TTY) 
OPEN(MYFILE  DISC) 

OPEN ( YOURFILE  DISC  PERM) 

OPEN (TAPE  3  1234) 

0PEN(TAPE2  0  WRITE) 

OPEN ( SCOPEX  5) 

OPEN ( SCOPEX  5  HIGH) 


Meaning 

activates  teletype  file  TTYFILE 

activates  local  disc  file  MYFILE 

activates  permanent  disc  file  YOURFILE,  found  in 
inventory  as  file  YOURFI 

activates  read-only  tape  file  TAPE3  on  physical 
reel  12  3l* 

activates  read/write  tape  file  TAPE2  on  a  scratch 
tape 

activates  680  character  CRT  file  SCOPEX  on  physical 
CRT  console  5 

activates  2000  character  CRT  file  SCOPEX  on  physical 
CRT  console  5 


Before  opening  a  .file,  the  user  should  make  sure  that  the  physical  file  is 
available.  For  example,  make  sure  that  there  are  tape  units  available  before 
opening  a  tape  file,  and  make  sure  that  a  disc  file  of  the  proper  name  is 
available  to  the  user  and  on  the  disc  before  opening  a  disc  file  in  PERM  mode. 
If  these  precautions  are  not  observed,  an  error  return  from  OPENFILE  will  be 
generated. 


A  disc  file  name  within  TSS  can  consist  of  up  to  6  characters j  LISF  can  use  ary 
literal  atom.  Consequently,  if  a  LISP  program  uses  a  file  name  containing  more 
than  six  characters,  only  the  first  six  characters  are  meaningful  to  TSS.  E.g., 
DISK001  as  a  file  name  in  LISP  becomes  DISC00  in  TSS,  and  hence  is  identical, 
as  far  as  TSS  is  concerned,  with  file  name  DISC002.  One  final  remark  concern¬ 
ing  disc  files  is  that  a  penaanent  disc  file  can  be  opened  only  if  it  belongs 
to  the  user,  or  is  public,  or  is  allowed  to  the  user.  It  can  be  read  and 
written  by  a  user  if  <t  belongs  to  him,  is  allowed  to  nim,  or  is  public  and  not 
protected  from  reading  or  writing.  Any  attempt  to  read  a  read-protected  file 
or  write  on  a  write-protected  file,  cr  to  open  a  private  file  in  PERM  mode,  will 
result  in  an  error. 


The  atom  #FILES*  contains  as  its  value  a  li.t  of  all  active  file  names. 
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3.2  FILE  DEACTIVATION 

Whenever  a  file  is  no  longer  needed,  it  should  be  deactivated  so  that  its  core 
storage  can  be  returned  to  the  LISP  system  and  the  physical  file  unit,  i.e., 
tape,  disc,  or  CRT,  can  be  released.  For  temporary  disc  files,  it  is  essential 
to  deactivate  the  file  in  order  to  add  the  file  name  to  the  user's  disc  inventory. 
File  deactivation  can  be  accomplished  through  the  macro  SHUT • 

SHUT  (f  d) 

SHUT  is  a  LISP  macro  that  expands,  using  the  function  *SliUTF,  into  the  primitive 
SHUTFILE  described  in  Section  5,  Like  OPEN,  it  returns  as  its  value  a  list  of 
all  currently  active  file  names.  Again,  f  is  the  name  of  the  file}  it  is  tc 
be  deactivated  and  must  previously  have  been  used  with  OPEN  to  activate  the  file. 
Whenever  any  file  is  shut,  its  buffer  storage  is  reclaimed,  and  the  associated 
unit  is  released  (physical  tape  or  CHT  and  reserved  disc  trucks).  The  argument 
d  is  optional  and  can  be  absent}  it  is  only  used  to  specify  the  disposition  of 
a  disc  file  and  is  ignored  for  other  tnan  disc  files.  For  disc  files  only,  if 
d  evaluates  to  the  reserved  word  DELETE,  the  file  is  purged  from  the  disc  inven¬ 
tory.  For  disc  files  only,  if  d  is  absent  or  is  not  the  reserved  word  DELETI  , 
the  file  is  purged  from  LISP  (its  buffer  storage  is  reclaimed);  however,  it  i.. 
saved  on  the  disc  and  the  first  six  characters  of  the  file  name  f  are  place  1 
in  the  user's  disc  inventory  as  the  name  of  this  file.  The  file  may  subsequent  1 
be  reactivated  vith  OPEN  by  OPEN  (f  DISC  PER.i)  where  f  is  the  file  name. 

The  user  is  cautioned  that  SHUT  does  no*  write  an  end-of-file  or.  either  tape 
or  disc:  the  user  must  do  this  himself  using  POSITION  (f  VEOF),  Note  that 
for  simple  uses  of  OPEN  and  SHUT  with  disc  files  (i.e.,  optional  parameter  is 
absent),  the  user  is  protected  against  unintentional  disruption  or  loss  of 
permanent  disc  files.  For  example: 

OPEN(f  DISC)  activates  a  temporary  file 
SHUT(f)  saves  file  as  a  permanent  file 

In  other  words,  one  must  take  positive  action  with  both  OPEN  and  SHUT  to  acce^j 
or  destroy  a  file,  respectively.  In  this  regard,  to  free  disc  storage  conges*  ;or. 
and  as  a  courtesy  to  other  users,  always  use  SiiUT(f  DELETE)  to  remove  unwante  : 
disc  files. 

Note  further,  that  if  you  QUIT  LISP  with  files  still  active  (no  SHUT  used  or. 
them),  all  CRT,  TTY,  tape,  and  temporary  disc  files  are  deleted  and  all  perma¬ 
nent  disc  files  are  saved.  When  a  disc  file  is  saved,  its  contents  or.  disc  are 
as  of  the  last  time  it  was  written.  This  scans  that  if  no  end-of-file  was 
written  before  the  QUIT  occurred,  the  disc  file  will  ir.  general  be  unreadable. 

Note  that  all  permanent  disc  files  craated  by  LISP  through  the  SHUT  function 
are  private,  write-protected  files.  To  change  their  sode  to  public,  or  to 
change  the  protection  mode,  the  user  suit  use  the  appropriate  TSS  commands, 
given  directly  to  the  TSS  executive,  not  to  LISP. 
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3.3  FILE  SELECTION 

Except  for  CRT  files  (which  are  really  binary  files  whose  primitives  are  de¬ 
scribed  in  Section  3.6)  active  files  may  be  selected  and  a  prior  file  de¬ 
selected  for  writing  or  reading  by  use  of  two  primitives,  VRS  and  RDS,  respectively. 

RDS(f) 

RDS  is  entirely  analogous  to  WRS,  but  for  input  file  selection. 

WRS(f) 

Argument  t  is  the  name  of  the  active  file  being  selected  for  output.  The 
value  of  WRS  is  the  name  of  the  active  output  file  being  deselected.  When  a 
file  is  selected,  the  record,  line,  and  column  controls  for  the  deselected 
file  are  preserved  with  that  file,  and  the  new  file  record,  line,  and  column 
controls  are  reestablished.  Thus,  WRS  may  be  used  with  complete  freedom  at 
any  time,  even  following  partially  composed  lines. 


Note  that  WRS  called  by  a  LISP  user  affects  only  the  user's  program  and  does 
not  confuse  the  supervisor;  all  supervisor  outputs  are  still  given  on  the 
teletype  console.  For  example: 

OPEN  (OUTTAP  0  WRITE)  opens  scratch  tape  under  name  OUTTAP 

$  WAIT  1  ^ 

>  TSS  replies 

$FILE  OUTTAP  DRIVE  12  REEL  0000 J 


(OUTTAP  *TTY) 
WRS  (OUTTAP) 
*TTY 


LISP  reply,  value  of  OPEN 
User  write  selection 
Value  of  WRS 


(LAMBDA  (A) 

(PROG  ()  (PRINT  A)  (RETURN  (FIRST  A)))) 
((NOW  IS  THE  TIME  FOR  ALL  GOOD  MEN  TO  COME 
TO  THE  AID  OF  THEIR  PARTY)) 


User's  program  for  test 


WRS  (*TTY) 
OUTTAP 


LISP  supervisor  reply  when  tape  has  been 
written  with  (NOW  IS  THE  ...  PARTY) 

User  write  selection 

Value  of  WRS 


Note:  If  a  file  is  shut  while  selected  for  either  read  or  write,  the 
selection  reverts  to  the  NIL  file,  a  -celetype  file  used  by  ERROR, 
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3.U  FILE  CONTROL 

POSITION  (f  m) 

POSITION  is  a  LISP  1.5  function  that  is  useful  for  controlling  active  tape  and 
disc  files;  it  acts  as  a  NOP  for  CRT  and  TTY  files.  Argument  f  is  the  name  of 
an  active  file,  and  argument  m  is  a  reserved  word  describing  the  action  desired. 
These  actions  are  tabulated  below.  (Note  that  any  other  value  of  m  d,es 
(TEREAD)  on  the  file  f.) 


m 

Tape  Action 

Disc  Action 

SKIPR 

Position  file  to  first 
next  record. 

line 

Position  file  to 
next  sector. 

first  line  of 

SKIPF 

Position  file  to  first 
of  next  file. 

line 

Position  file  to  the  end-of-file 
and  erase  end-of-file. 

WEOF 

Write  tape  end-of-file 

• 

Write  disc  end-of-file. 

WEOT 

Write  tape  end-of-tape 

« 

Same  as  WEOF. 

REWIND 

Position  file  to  first 
of  first  file. 

line 

Position  file  to 
file. 

first  line  of 

BACKR 

Position  file  to  first 
of  prior  record. 

line 

Position  file  to 
prior  sector. 

first  line  of 

BACKF 

Position  file  to  first 
of  prior  file. 

line 

Same  as  REWIND. 

For  POSITION,  tape  records  and  disc  sectors  (there  are  eight,  512-vord  sectors 
per  disc  track)  are  treated  alike.  Furthermore,  only  one  physical  file  may 
exist  in  a  logical  disc  file,  whereas  multiple  physical  files  may  exist  in  a 
logical  tape  file. 

POSITION  returns  one  of  four  possible  values  according  to  the  action  taken: 

1.  f  is  returned  if  m  is  not  a  SKIPR  or  SKIPF.  If  m  is  SKIPR 
or  SKIPF^he  following  values  derive, 

2.  A  positive  integer,  representing  the  number  of  records 
(or  sectors)  skipped  (not  counting  an  end-of-file  record), 

3.  The  atom  EOF  if  the  next  record  on  tape  (or  the  current 
sector  on  disc)  is  an  end-of-file, 

U,  The  atom  EOT  if  the  next  tape  record  is  an  end-of-tape. 
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Note:  You  can  never  POSITION  or  READ  past  the  end-of-file  on  a  disc  file  since 
a  uisc  file  always  contains  only  one  physical  file.  You  are  permitted  to  do  so 
with  tape  files,  at  your  own  risk,  since  they  may  contain  multiple  physical  files. 

TABlN(n) ,  TABOUT(n) 

These  primitives,  TABIN  and  TABOUT,  may  be  used  for  format  reading  and  writing, 
respectively.  They  advance  (forward  or  backwards)  the  column  pointer  of  the 
selected  file  to  column  n,  where  n  is  a  positive  integer  less  than  71.  (For  n 
outside  the  range  1  s  n  *  70,  a  value  of  n  *  1  is  assumed.)  For  example, 
TABOUT(33),  will  tab  tne  output  line  to  column  33*  and  subsequent  printing  will 
begin  at  that  column. 

Both  primitives  return  a  positive  integer  value,  corresponding  to  the  column  number* 
prior  to  the  tab. 

TABIN  and  TABOUT  do  not  influence  the  data  content  of  any  line,  and  may  be  used 
to  backup  or  skip  forward  within  a  line  without  disturbing  the  contents. 

3.5  I/O  PRIMITIVE  CHANGES 

To  accommodate  the  new  I/O  mechanisms,  a  number  of  existing  primitives  have 
been  modified  in  their  side-effects  only. 

TERPRI  (  ) 

TERPRI  new  performs  as  follows: 

1.  Write  an  end-of-record  mark  in  the  current  line  of  the  selected 
output  file. 

2.  Move  the  current  line  to  the  next  available  "slot"  in  the 
internal  record  of  the  selected  output  file. 

3.  Write  the  internal  record  of  the  selected  output  file  onto 
the  associated  external  unit. 

4.  Clear  the  current  line  to  blanks  and  reset  the  column 
control  to  1  for  the  selected  output  file. 

5.  For  tape  files,  position  file  to  the  next  record.  For  disc 
files,  position  file  to  the  next  sector  only  if  the  current 
sector  is  full. 
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Thus,  TERPRI  prints  each  teletypewriter  line  it  sees;  it  writes  blocked  tape 
records  of  variable  length,  up  to  30  lines  per  record,  whenever  it  is  called; 
and  it  writes  blocked  disc  records,  packed  fully  to  hi  lines  per  record,  when¬ 
ever  evaluated.  A  special  TERPRI,  called  STERPRI,  is  available  that  always 
blocks  maximum  size  records,  thus  speeding  production  runs. 

STERPRI  (  ) 

STERPRI  performs  as  follows: 

1.  Move  the  current  line  to  he  next  available  slot  in 
the  internal  record  of  the  selected  output  file. 

2.  If,  and  only  if,  the  internal  rrcord  is  full,  write 
it  out  on  the  fisociated  external  unit, 

3.  Clear  the  current  line  to  blanks  and  reset  the  column 
control  to  1  for  the  selected  output  file. 

Note:  Whenever  STERPRI  has  been  used  in  output  formatting,  TERPRI  must  be 
called  finally  to  print  the  last  partial  record  from  the  output  buffer. 

•RATOM  (  ) 

The  basic  atom  read  primitive  *RAT0M  is  used  by  all  read 
functions,  and  it  has  been  modified  to  read  from  the  select ea 
input  file,  End-of-mediura  conditions  are  flagged  by  •RATOM  as 
follows : 

Unit  Condition  *RAT0M  Effect 

TTY  end-of-line  ring  bell  for  more  input 

(carriage  return) 

DISC  end-of-file  return  literal  atom  EOF 

tape  end-of-file  return  literal  atom  EOF 

tape  end-of-tape  return  literal  atom  EOT 

READ,  READ1  and  READCH  which  use  *RAT0M,  read  from  the  selected  input 
TEREAO  also  works  on  the  selected  input  filr. 
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PRINl(a) 

The  basic  atom  print  primitive,  PRIN1  is  used  by  all  print  functions  and  it 
has  been  modified  to  write  in  the  selected  output  file.  Disc  files  will 
automatically  grow  larger,  by  one  track,  whenever  printing  overflows  the  last 
sector  (subject  to  the  availability  of  free  disc  tracks).  PRIN0 ,  which  uses 
PRIN1,  similarly  works  on  the  selected  output  file,  as  does  PRINCHO. 

3.6  SCOPE  FUNCTIONS 

The  scope  functions  described  here  are  used  to  plot  displays  on  the  dd-19  CRT 
display  consoles  and  to  accept  light-pen  inputs.  Scope  files  are  opened  Just 
as  other  files;  however,  scope  files  are  never  selected  by  WRS  or  RDS  but 
rather  use  the  following  primitives: 

PLOT  (f  i  s) 

Procedure  PLOT  inserts  a  vector  or  character  specified  in  list  i 
into  the  file  f  based  on  a  search  criterion  specified  in  list  s. 
The  search  is  made  bv  comparing  for  equality  all  non-NIL  items  in 
s  with  data  already  in  file  f.  If  s  ■  NIL,  search  is  for  first 
available  word  in  file  f .  If  the  search  fails,  the  value  of  the 
procedure  is  NIL.  If  successful,  the  value  of  the  procedure  is 
a  list  1  of  the  contents  of  the  search  match  word  of  file  f. 

The  form  of  i,  s,  and  1  is: 

( (x.Ax)  (y.Ay)  (char  .  size)  id  ) 

where; 

x  and  y  must  satisfy  0  $  x,  y  S  1023 

Ax  and  Ay  must  lie  in  the  range  -127  S  x,  y  f  ♦  127 

char  »  a  character  atom 

size  must  lie  in  the  range  0-3  where  0  designates  the 
smallest  character  size,  and  3  indicates  the  largest 
size  character  (size  is  ignored  for  vectors). 

For  id,  the  following  conventions  are  used: 

1  *  Scope  1  or  1* 

2  ■  Scope  2  or  5 

3  ■  Scopes  (1  and  2)  or  (U  and  5) 

1*  »  Scope  3  or  6 

5  ■  Scopes  (1  and  3)  or  (U  and  6) 

6  »  Scopes  (2  and  3)  or  (5  and  6) 
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7  ■  Scopes  (1,  2  and  3)  or  (1*,  5,  and  6) 

Note  1:  A  vector  is  designated  when  either  Ax  or  Ay  is  not 
NIL,  and  char  *  the  character  atom  blank  (’b). 

Note  2:  To  display  data,  PRINTCRT  must  be  used.  The  scope 
number  in  OPEN  determines  whether  Scopes  1,  2,  3 
or  1*,  5,  6  are  used. 

Example: 

PLOT  (BUFFI 

((100  .  127)  (100)  (*b)  k) 

((NIL)  (1*53)  (E)  1*)) 

This  will  enter  a  maximum  sized  vector  for  display  or. 

Scope  3  (or  6)  at  coordinate  (100,  100)  if  in  file 
BUFFI  there  is  found  on  Scope  3  (or  6)  an  E  at  any 
column  of  row  1*53.  Note  that  any  x  or  SIZE  will 
satisfy  the  search,  since  these  parameters  were  NIL. 

If  the  whole  third  argument  of  PLOT  were  NIL  (s  «  NIL), 
then  the  vector  would  be  inserted  at  the  first  empty 
entry,  i.e.,  a  search  for  first  NIL  entry  of  the  file. 

PRINTCRT  (f) 

PRINTCRT  dumps  the  file  named  f  on  0-32  drums  for  display 
on  the  SDC  scope.  The  value  of  the  procedure  is  NIL  if 
print  is  not  possible;  otherwise  the  value  is  f. 


READCRT  (f) 

READCRT  is  used  to  obtain  a  light-pen  input  from  LISP 
file  f.  After  the  user  lightpens  a  character  or  vector 
on  the  CRT,  READCRT  returns  a  list  of  the  information 
describing  that  character  or  vector  in  the  same  format 
used  for  PLOT  i  or  a;  i.e.,  READCRT  returns  a  list  of 
the  form 

((x  .  Ax)  (y  .  Ay)  (char  .  sire)  id)  . 
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3.7  T.TBRARY  FUNCTIONS 

All  of  the  library  functions  of  Mod.  2,3  have  disappeared  from  Mod.  2.6. 
As  a  result  of  availability  of  the  LISPED*  program  for  file  editing  and 
manipulation,  ve  have  found  that  most  library  functions  are  more  readily 
performed  with  LISPED,  The  following  three  functions  have  been  added  to 
Mod.  2.6  to  facilitate  the  loading  (operation)  of  LISPED  files  into  LISP: 

LOADEXP  (filename) 

Performs  loading  (operation)  of  a  single  LISPED  file  (one 
S-expression  in  the  format 

(n*m.  fl  ‘l  f2  a2  “•  fn  an>  • 

where  name  is  an  arbitrary  name,  and  a^  are  function  and 
arguments  constituting  an  Evalquote  pair) 

filename  is  the  name  used  in  OPEN. 

(Note  that  the  file  must  be  opened  before  LOADEXP  is  called,) 
LOADEXP  does  its  own  read  selection  using  RDS.  LOADEXP 
prints  the  value  of  each  Evalquote  pair  on  the  user's  console, 
and  returns  name. 

READFILE  (filename) 

Reads  all  S-expressions  on  the  file  designated  by  filename. 
and  returns  a  list  of  the  expressions  read.  READFlLE  does 
its  own  read  selection  using  RDS, 

PRINTFILE  (filename  list) 

Prints  onto  the  file  filename^  each  S -expression  in  list,  and 
then  writes  an  end-of-file  on  the  file  filename.  pETNTPILE 
does  it 8  own  write  selection  using  WRS. 


« 


LISPED  is  described  in  TM-2337/100/01 


11  April  1966 


IT 


T!  1-2337/  lui.  M 


1*.  SYSTEM  MODIFICATIONS 

The  LISP  1.5  Mod.  2.6  operating  system  consists  of  an  initialization  packu^e 
and  a  supervisor  which  differ  from  those  in  the  previous  version  of  Llf^, 

l».l  HITTALI ZATIOH 

The  initialization  package,  called  whenever  the  user  says  GO  after  loading, 
consists  of  the  function  MIOINIT(),  which 

1.  Cleans  up  the  system  by  removing  all  previous  file  declarations 
and  file  buffers  from  LISP  memory,  by  using  the  function 
•IOSHUT  to  delete  all  files  found  as  the  value  of  *FILES*. 

2.  Makes  a  file  declaration  for  the  file  *TTY  that  is  used  by 
the  supervisor;  sets  *TTY  to  the  value  (QUOTE  *TTY);  and  sets 
the  variables  *TRDS  and  *TWRS,  which  govern  the  input  and 
output  from  the  supervisor,  to  *TTY, 

It.  2  SUPERVISOR 

In  general,  the  LISP  1.5  Mod.  2.6  supervisor  performs  the  sane  function  as  the 
LISP  1.5  Mod.  2.5  supervisor,  and  allows  the  same  input  flexibility,  including 
the  use  of  *FUHC  to  refer  to  the  last  top-level  function  compiled  into  scratch 
program  area.  However,  the  operation  is  smoother  and  more  efficient,  and  the 
functions  *BEFQ,  sad  *NG8YM  are  not  used. 

*supv  *SUPV( )  is  the  LISP  supervisor,  which  does  a  RDS 

(•TTY)  and  WRS  (*TTY)  and  thereafter  does  a  loop 
using  *TEVALQT. 

(*SUPV  (LAMBDA  ()  (PROG  (X  Y) 

(RDS  *TTY) 

(WRS  *TTY) 

A  (TEREAD) 

(SETO  X  (READ)) 

(SETQ  X  (READ)) 

(SETQ  Y  (READ)) 

(TEREAD) 

(PRINT  (*TEVALQT  XT))  (GO  A)))) 
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•TEVALQT  (x  y) 

•TEVALQT  performs  housekeeping  of  scratch  program  space  and 
of  read-selection  and  vrite-selectlon  and  calls  ^tVALQT  as  follows t 

(•EVALQT  X  Y  (QUOTE  *FUNC)) 

•EVALQT  (x  y  n) 

•EVALQT  works  as  it  did  in  Mod,  2.5»  except  that  whenever  the 
third  argument  is  identically  (QUOTE  *FUNC) ,  a  sweep  is  made 
through  the  atom  head  and  quote  cell  area,  removing  the 
bindings  of  all  atoms  that  point  into  the  scratch  program 
area,  and  removing  all  temporary  quote  cells. 

U.3  GROWING  PAINS 

In  LISP  1,5  Mod*  2.6,  the  highei  address  boundary  of  binary  program  space 
(BPS)  is  not  fixed,  but  is  moved  by  LAP  whenever  a  new  program  being  compiled 
at  any  time  would  otherwise  overflow  the  current  boundary  of  BPS,  This 
"growing  pain"  is  accomplished  by  the  function  FIXEM,  which  relocates  all 
full  word  space  structures  toward  higher  core  addresses,  and  adjusts  all 
code  references  to  full  word  space  and  binary  program  space  boundaries 
appropriately. 

The  amount  by  which  BPS  is  adjusted  on  each  application  of  FIXEM  is  determined 
by  the  value  of  the  atom  *BUMP.  The  value  of  •BUMP  in  the  standard  LISP 
system  is  1Q3  or  512,  In  assembling  a  very  long  function,  LAP  may  call  FIXEM 
repeatedly. 

Whenever  FIXEM  is  called,  the  message 
(n  IS  NEW  TBPS) 
is  printed  on  the  teletype. 

Since  the  system  boundaries  change  continuously,  and  free  space  may  be  used 
for  binary  programs,  full  word  storage,  or  list  storage,  the  user  can  find 
out  the  amount  of  available  space  by  calling  the  function  FREESPACE  (). 

FREESPACE  () 

FREESPACE  ()  calls  the  garbage  collector,  then  computes  the 
amount  of  available  free  storage,  and  prints  the  result  as 
a  decimal  integer. 

The  value  of  FREESPACE  ()  in  a  clean  LISP  system  is 
approximately  29,000  cells. 
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5.  PRIMITIVES 

OPENFILE  (f  b) 

OPENFILE  creates  a  file  whose  name  is  the  first  six  characters 
of  the  literal  atom  f.  OPENFILE  returns  f  as  its  value. 
Argument  b  is  a  list  of  property-value  pairs  describing  the 
file.  The  requisite  pair  information  is  tabulated  below. 


Property-Value  Pairs  for  OPENFILE 


Properties  TTY 


8 


UNIT 


m  a  _  _ 


FORM  19  (BCD)  18  (binary) 

19  (sortable) 


18  (binary)  18  (binary) 

19  (sortable) 


SIZE  10 


10n(l  5  n  .«  30), (BCD) 
var iab 1 e , ( b i nary ) 


reel  no. 


NIL  (read-only) 
T  (read/write) 


k0g6 


680n(l  j  n  <  }) 


NIL( permanent ) 
T  (temporary) 


BUFF  GENSYM-named  buffer  supplied  by  OPENFILE 


OPENFILE  places  the  list  of  above  property  value  pairs 
as  the  value  of  property  10  on  the  property  list  of  file. 


Property-value  pair  not  required 


OPENFILE  does  four  things: 


1.  It  creates  an  internal,  GENSYM-named  buffer  of  specified 
size,  with  all  the  necessary  control  mechanisms  for  the 
unit  specified. 

2.  It  sets  up  all  the  necessary  I/O  cossiunication  linkages 
with  the  time-sharing  monitor. 

3.  It  attaches  list  b  (augmented  by  the  property-value  pair 
"BUFF"  and  GENSVM-naned  buffer)  as  the  value  of  property 
"10"  on  the  property  list  of  f. 

k.  It  returns  a  list  of  all  file  names  opened  to  date. 
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lot*!  For  DISC,  &  MODE  value  of  NIL  (permanent)  mean*  that  the  specified  file 
already  exists  as  a  permanent  disc  file  in  the  time-sharing  disc-file  inventory. 
T( temporary)  means  that  the  specified  file  does  not  already  exist  and  must  be 
created.  Disc  files  should  never  exceed  one  track  (1)096  vords) ,  since  for 
reading,  only  one  sector  (512  vords)  is  ever  in  core  at  any  moment.  For  print¬ 
ing  files  larger  than  one  track  (1*08  lines),  the  LISP  print  programs  vlll 
automatically  extend  the  file  slse  by  one  track  as  needed.  Therefore,  be 
frugal  vith  disc  slse  requests.  For  exsmple,  OFEHFILE  (TAPE1  (UNIT  3  FORM  23Q 
SIZE  300  ID  123*)  MODE  NIL))  vould  create  a  read-only  (MODE-NIL) ,  300  vord 
(SIZE-300),  sort  able  (FORM-23Q),  tape  (UNIT-3)  file,  on  reel  123»)  (ID-123U) 
named  TAPR1.  0PEN(TAPE1  123M  vould  achieve  the  same  result. 

■UTFILI  (f  b) 

SHUTFILE  deactivates  a  file.  It  returns  as  its  value  a  list  of  all  file  names 
still  opened.  It  purges  the  file,  whose  name  is  the  first  six  characters  of 
the  literal  atom  f,  from  both  the  LISP  system  and  the  time-sharing  I/O  com¬ 
munication  tables,  and  dismisses  the  unit  reserved  by  this  file.  The  property 
10  is  removed  from  the  property  list  of  the  atom  f .  The  argument  b  is  the 
disposition  mode  for  the  file  f  and  only  has  significance  for  disc  filea. 

If  b  -  NIL  (permanent),  the  file  f  will  be  deleted  from  the  LISP  system)  but 
the  name  and  contents  of  the  file  will  be  added  to  the  permanent  time-sharing 
disc  inventory.  The  contents  of  this  file  will  be  exactly  as  they  were  at  the 
time  of  the  last  TERPRI.  If  b  «  T(temporary) ,  the  file  f  will  be  deleted  from 
both  the  LISP  system  and  the  time-sharing  disc  inventory,  regardless  of  the 
OPENFILE  MODE  value. 

Therefore! 

1.  Always  evaluate  TERPRI  prior  to  SHUTFILE  to  dump  any 
leftovers  in  the  file  on  to  the  external  unit.  Then 
writ*  an  cnd-of-fil#  with  POSITION. 

2.  Permanent  disc  files  may  be  deleted  from  the  disc  by 
SHUTFILE  vith  b  •  T  (tmaporary). 

3.  Temporary  disc  files  nay  be  made  permanent  on  the  disc  by 
SHUTFILE  with  b  •  NIL  (permanent).  (Note:  0-32  time¬ 
sharing  permanent  disc  files  vill  be  automatically  deleted 
by  the  time-sharing  system  after  about  two  days  of  dormant 
residence.) 

h.  For  b  •  NIL  (permanent),  SHUTFILE  may  request  another  file 
nmme  under  which  to  save  this  file.  This  may  be  necessary 
because  of  a  name  conflict  vith  other  users'  permanent 
files  in  the  time-sharing  disc  inventory.  In  such  cases, 
all  future  LISF  references  to  this  file  must  us*  the  new  name. 
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(TNSTAT) 

TRSTAT  (transfer  status)  returns  as  its  value  the  status 
code  (an  integer)  of  the  last  I/O  transfer  according  to 
the  schedule  below.  It  is  useful  for  error  detection  and 
for  distinguishing  the  terminating  condition  with  READCK, 
or  any  READ  primitive. 

Status  Code  Condition 

S  3  End-of-line 

h  Lnd-of-file 

5  tnd-of-tape 

*  6  Transfer  errors 

Note  that  (TNSTAT)  can  meaningfully  be  used  only 
inside  a  program,  never  at  the  top  level  of 
Evalquote,  since  the  last  I/O  transfer  seen  by 
Evalquote  is  always  a  teletype  read. 

SQUOZE  (1) 

SQUOZE  is  a  primitive  used  by  function  COMPRESS.  The 
value  of  SOUOZE  is  a  literal  atom  formed  from  the  list 
of  character  atoms  l.  SOUOZE  is  undefined  if  i  is  anyth in* 
other  than  a  list  of  character  atoms. 


READC  (f  b) 

READC  is  a  primitive  used  by  EX*L0Dr,  The  value  of  REATf  is 
the  character  atom  at  the  bth  byte  (starting  with  0) 

of  the  print  name  of  literal  atom  f.  I:  b  exceeds  the 
maximum  byte  of  the  print  name  of  f,  READC  returns  the 
value  NIL. 


11  April  1966 


22 


TM-2337/103/0Q 


6.  ERROR  MESSAGES 

The  error  messages  given  in  Sections  6.1  and  6,2  are  LISP  error  messages 
vhich  result  in  a  LIS?  unwind,  so  that  in  general  the  user  can  continue 
his  operations  normally.  The  time-sharing  error  messages  given  in  Section  6.3 
require  special  action,  as  discussed  therein: 

6.1  INPUT /OUTPUT  ERROR  MESSAGES 


Message 


Meaning 


NO  FILE  Read  or  write  functions  do  not  find  an  internal 
buffer  for  the  currently  selected  I/O  unit.  This 
buffer  is  created  and  attached  to  the  property 
list  of  the  file  by  OPEN  (OPEN FILE)  . 


NO  SCOPE  The  CRT  is  currently  not  available  as  a  selectable 
I/O  unit  with  WRS  or  RDS.  The  SCOPE  may  be  used 
vith  functions  READCRT,  PRINTCRT,  and  PLOT. 


UKITEFR  Most  probably  caused  by  reading  or  writing  a  tape 
beyond  EOT,  or  beyond  last  EOF.  Also  induced  by 
trying  to  read  a  binary  tape  in  Hollerith  mode. 
May  also  be  induced  by  a  disc  or  unit  malfunction. 


UNITBUSY  Unit  requested  by  OPEN  (OPENFILE)— tape,  disc,  or  CRT— 
is  in  use  by  others  and  temporarily  unavailable. 

Type  ! TAPES  cr  or  1 TRACKS  cr  to  see  current  time¬ 
sharing  unit  availability.  Ouery  the  system  and  try 
again  if  either  query  shows  unit  availability. 


FILEGONE  Permanent  disc  file  named  with  OPEN  (OPENFILE)  or 

SHUT  (SHUTF1LE)  cannot  be  found  in  the  time-sharing 
disc  file  inventory.  Either  file  name  is  in  error, 
or  file  has  been  deleted  by  periodic  time-sharing 
system  purging  of  overloaded  disc. 


PREEMPTED  DISC  NAME  -  ENTER  ANOTHER  NAME 

The  temporary  file  named  with  OPEN  (OPENFILE)  cannot 
be  saved  under  that  name  by  SHUT  (SHUTFILE)  as  the 
name  conflicts  vith  an  existing  disc  file.  Enter 
another  file  name  for  this  file  following  this 
message.  SHUT  (SHUTFILE)  will  repeat  the  request 
until  successful. 


(x  NOT  OPENFILED) 

File  name  x  has  been  used  with  WRS  or  RDS  but  has  not 
been  opened  previously  with  pPEN  OPENFILE). 
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(UNIT  NOT  SPECIFIED) 

RDS  or  WRS  has  been  unable  tc  find  "UNIT”  on  the  value 
list  of  property  "10”  on  the  property  list  of  the  named 
file.  See  OPEN  (OPENFILE), 

(x  HAS  NO  BUFF) 

RDS  or  WRS  has  been  unable  to  find  "BUFF"  on  the  value 
list  of  property  "10"  on  the  property  list  of  file  x. 

See  OPEN  (OPENFILE). 

6.2  OTHER  LISP  ERROR  MESSAGES 

(CAR  NIL  UNDEFINED) 

CAR  of  a  character  atom  is  undefined. 

(CDR  NIL  UNDEFINED) 

CDR  of  a  character  atom  is  undefined. 

(EXPLODE  x  UNDEFINED) 

EXPLODE  error  if  x  is  a  nonatomic  S-expression. 

(COMPRESS  x  UNDEFINED) 

COMPRESS  error  if  x  is  a  list  of  other  thas  character 
atoms . 

(x  REDUNDANT  FILE  NAME) 

A  file  vith  the  same  file  name  has  already  been  opened 
by  OPEN  (OPENFILE).  Try  another  file  name. 

x  NOT  BOUND  AS  FN 

This  usually  means  that  x  has  been  called  as  a  function 
without  having  been  defined.  Correct  the  condition  and 
try  again. 

x  SETQ’ED  -  NOT  BOUND 

This  usually  means  that  an  attempt  was  made  to  per fora 
(SETQ  x  expression)  where  x  was  neither  bound,  nor 
CSET  previously.  To  use  a  variable  free,  it  must  be 
given  a  CSET  (or  CSETO)  previously.  SPECIAL((x))  will 
not,  solve  the  problem,  but  CSET  (x  NIL)  will, 

(CORD  ERROR  A3) 

CORD  used  in  expression  context  had  no  true  clause,  and 
evaluation  "fell  through"  at  run  time. 

((PAIR  ERROR  T2)  x  y) 

((PAIR  ERROR  F3)  x  y) 

The  function  PAIR  was  called  with  lists  of  unequal  length. 
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(x  MOT  AN  ATOM  (CSET)) 

First  argument  given  to  CSETO  was  not  a  literal  atom,  or 
first  argument  of  CSET  did  not  evaluate  to  an  atom. 

(OUT  OF  SCRATCH) 

LAMBDA- express  ion  given  to  Evalquote  was  too  long  to 
compile  into  scratch  program  area:  define  the  function, 
then  call  it. 

(x  HOT  A  NUMBER) 

An  attempt  was  made  to  use  a  non-numeric  argument  for 
an  arithmetic  function. 

(x  NOT  A  LABEL  (COMFROG)) 

The  expression  (GO  x)  was  encountered  in  a  PROG  where 
x  was  not  used  as  a  label.  The  function  must  be 
corrected  and  redefined. 


(SET  ILLEGAL) 

SET  is  not  defined  in  0-32  LISP  1.5. 

(x  NOT  FUNCTION) 

x  is  an  expression  other  than  (LAMBDA  ...)  or 

(LABEL  ...  (LAMBDA)),  used  in  a  context  where  a  LAMBDA- 

expression  is  called  for,  e.g. 

DEFINE  !((AB») 

will  not  work,  although 

DEFINE  (((A  (LAMBDA  (Y)  (B  Y))))) 

v.ill, 

(x  NOT  DECLARED) 

This  message  is  printed  by  the  compiler  during  compilation, 
au  a  warning  only.  It  means  that  x  was  used  free  without 
having  been  declared  SPECIAL  before  compilation,  or  was 
used  as  a  functional  argument  without  being  preceded  by 
the  word  FUNCTION,  This  is  the  only  compilation  error 
message  which  does  not  prevent  completion  of  compilation, 
since  the  compiled  code  may  be  correct. 
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For  example: 

(LAMBDA  (X)  (MAPCAR  X  ADD1 ) )  ((0  1  2)) 
vill  work,  but  the  message  : 

(ADD1  NOT  DECLARED) 
vill  occur. 

(LAMBDA  (X)  (MAPCAR  X  (FUNCTION  ADD1 ) ) )  ((012)) 
vill  not  produce  the  error  message. 

Similarly, 

DEFINE  (( 

(AA  (LAMBDA  (X)  (CSETQ  B  X))) 

(BB  (LAMBDA  (Y)  (CONS  (AA  Y)  B))))) 

/ 

vill  produce  the  error  message; 

(B  NOT  DECLARED) 

during  compilation,  even  though  the  function  BB  cannot 
cause  an  error. 


*  0 
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RESCUE  n 

The  meaning  of  this  error  message  is  given  in  the 
following  table: 


£ 

1 

2 

3 

It 

5 

6 

7 

8 

9 

10  or  * 

11  or  ■ 

12  or  V 

13  or  " 


Meaning 

Illegal  branch  to  FIX  program 
Illegal  Instruction 
Illegal  address  reference 
Illegal  division 
Program  halt 
BCH  ZERO  -  tape  write 

Wrong  mode  -  tape  read 
Memory  protect  violation 
Illegal  PER  instruction 
I/O  trap 

Attempt  to  store  into  input 
memory 


Remarks 

(1) 

(1) 

(2) 

Attempt  to  divide  by  zero 

(1) 

Should  never  occur  unless 
LISP  is  bad 

Wrong  tape  mounted? 

(1) 

(1) 

(1) 

(1) 


Memory  protect  register  or  (1) 

Interrupt  content  register  store 

Manual  Break  action  Break  key  or  'STOP  used 


'  *  These  rescue  messages  should  never  occur  unless  the  user 
has  used  LAP  incorrectly,  nr  unless  the  system  has  been 
damaged  in  some  way. 

(2)  7Ms  message  will  not  usually  appear.  Instead,  LISP 
will  print  out  one  of  the  two  messages, 

x  S ETC  ©  -  NOT  BOUND  or 

X  NOT  BOUND  AS  FUNCTION 

depending  upon  -Aether  an  illegal  store  or  an  illegal 
indirect  Jump  was  encountered,  x  is  usually  an  atom 
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6.3  TIME-SHARING  ERROR  MESSAGES 

The  following  tine-sharing  error  messages  may  be  encountered  by  the  user  dur 
to  his  attempt  to  shut  or  write  on  a  write-protected  public  disc  file  which 
is  not  his  own,  or  to  read  a  read-protected  disc  file  which  is  not  his  own. 

$  NO  PILE  LISP  000nnnnn  DISPATCHER  CALL  ERROR 

$  BAD  MOVE  LISP  000nnnnn  DISPATCHER  CALL  ERPOP  »*** 

The  program  will  at  this  point  be  trapped  by  the  Time-Sharing  System.  To 
extricate  himself  from  this  situation,  the  user  will  then  have  to  reload  o'- 
else  execute  the  following  set  of  time-sharing  commands. 

I$LIV»U0002'*  'cr  reset  live  register 

$MSG  IN.  TSF  reply 

GO  "go"  command  to  TSS 

LISP  will  output  two  bells  when  it  is  ready  to  receive  more  input.  If  the 
user  does  not  receive  two  bells  he  must  reload  to  continue. 
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